Back to Main Menu

Update Assessment Form Result

Introduction

The following Assetic REST API endpoint may be used to update an existing assessment form result:

  • PUT /api/v2/assessmentformresult/{id}

 

This API requires the GUID of the assessment form result to be known, represented as {id} in the above request endpoint.

 

If the GUID of the assessment form result is unknown it is possible to configure a saved Search Profile for an assessment form definition, and include "Form Result Guid" as a field in the search results. The integration article Using Advanced Search Profile outlines how to construct a saved search profile for integration purposes, which can be used in this scenario to retrieve one or more assessment form results for the purposes of performing an update request.

 

Assessment Form Result Definition

When updating an assessment form result, the following properties are relevant:

Property Description Type Sample
Id

The unique Assetic GUID, which identifies the assessment form result.

Must be included in the request body and the request URL.

 GUID "Id": "ff6638a0-a583-43b3-9e4e-af6239f4fd43"
FormId

The unique identifier of an assessment form definition, which defines the control widgets that the form result data is applied against.

Refer to the integration article Get Assessment Forms for information on retrieving an assessment form definition.

 GUID "FormId": "9680546d-4f56-e711-8187-025500ccdddb"
FormResultStartTime

The date the assessment form result begins.

 DateTime "FormResultStartTime": "2023-01-01T00:00:00"
FormResultEndTime

The date the assessment form result ends.

 DateTime "FormResultEndTime": "2023-01-31T23:59:99"
FormResultLastModified

The date the assessment form result was last modified.

Use the current DateTime.

 DateTime "FormResultLastModified": "2023-01-06T12:50:12",
FormResultStatus

The current status of the assessment form Result.

0="Active"

100="Inactive"

 Integer "FormResultStatus": 0
FormResultComment

General comments for the assessment task.

4000 character limit.

 String "FormResultComment": "Example Comment"
FormResultSkipped

Specify if the assessment result was skipped or not.

Boolean 'true' or 'false'.

 Boolean "FormResultSkipped": false
FormResultRsResourceIdAssessedBy

An object containing the "Id" (GUID) and "DisplayName" (STRING) properties for the resource that gathered the assessment result data.

Note that it is not possible to alter the existing Resource, and as such the existing Resource details should be provided.

See the Get Resources article for additional information on retrieving resource details.

 Object

"FormResultRsResourceIdAssessedBy": {"Id": "3c5dab0b-3af9-4100-a2c2-4b7527dbb202","DisplayName": "Assetic System"}
Data

An object containing the assessment data, for all controls defined in the parent assessment form definition.

Properties within the object are defined as key-value pairs, where the assessment form control name is the key and the value is the data supplied by the assessor.

Additional information about a specific form's controls can be obtained by retrieving its definition, as described in the article Get Assessment Forms

 Object "Data": {"C0616ee451ca64fd8aed2b85885a1e08e": "Example Text Value","C0cc9c225ccea445bbc43e96b3560083b": "Example Text Area Value","C59d636e47dd4423f9bad07da82aec454": 1,"C608a43fee61b4a118b64f8aeed658b5a": "2023-02-03T01:14:42","C1878625b38d74d66a8ed3ad7add738b2": "2023-02-03T01:14:42","C80b329352e3441eabd120db9523a1339": "Dropdown Value"}
ParentEntityId The unique system-generated identifier for the parent Assessment Task that the form result has been applied against. GUID "ParentEntityId": "064a8546-7966-4ef4-a9c7-6ae06f934e74"

 

Note: The Assessment Form Result PUT endpoint does not support partial updates, so the update payload must include all editable fields with either their current value or the new/modified value. This is particularly noteworthy for the "Data" object property, and omitting this property from the payload will clear the assessment form result of all specified control widget data/values.

Sample Payload

The following is an example payload used to update an existing Assessment Form Result.

Sample Request

In this example payload, an assessment form result is being updated and the 'FormResultStatus' is being set to 'Inactive' (100). The 'FormResultComment' property of the payload is also being updated to indicate that the form result has been set to inactive:

https://[yoursite].assetic.net/api/v2/assessmentformresult/ff6638a0-a583-43b3-9e4e-af6239f4fd43
{ 	"Id": "ff6638a0-a583-43b3-9e4e-af6239f4fd43", 	"FormId": "9680546d-4f56-e711-8187-025500ccdddb", 	"FormResultStartTime": "2023-02-02T00:00:00", 	"FormResultEndTime": "2023-02-07T23:59:59", 	"FormResultLastModified": "2023-02-07T02:20:03", 	"FormResultStatus": 100, 	"FormResultComment": "This form result has been set to inactive", 	"FormResultSkipped": false, 	"FormResultRsResourceIdAssessedBy": { 		"Id": "3c5dab0b-3af9-4100-a2c2-4b7527dbb202", 		"DisplayName": "Assetic System" 		}, 	"Data": { 		"C0616ee451ca64fd8aed2b85885a1e08e": "Example Text Value", 		"C0cc9c225ccea445bbc43e96b3560083b": "Example TextArea Value", 		"C59d636e47dd4423f9bad07da82aec454": 1, 		"C608a43fee61b4a118b64f8aeed658b5a": "2023-01-18T09:17:57", 		"C1878625b38d74d66a8ed3ad7add738b2": "2023-05-22T16:17:57", 		"C80b329352e3441eabd120db9523a1339": "Dropdown Value 1" 		}, 	"ParentEntityId": "064a8546-7966-4ef4-a9c7-6ae06f934e74" }

Sample Response

The response code is 200 if the update is successful, and a collection is returned including the changes made to the assessment form result:

{     "Id": "ff6638a0-a583-43b3-9e4e-af6239f4fd43",     "FormId": "9680546d-4f56-e711-8187-025500ccdddb",     "FormName": "BUILDINGASSESSMENT",     "FormLabel": "Building Assessment",     "FormVersion": 1,     "FormApplicableLevel": 2,     "FormResultId": 2808,     "FormResultStartTime": "2023-02-02T00:00:00",     "FormResultEndTime": "2023-02-07T23:59:59",     "FormResultLastModified": "2023-02-07T02:20:03",     "FormResultStatus": 100,     "FormResultComment": "This form result has been set to inactive",     "FormResultSkipped": false,     "FormResultSkippedReason": 0,     "FormResultRsResourceIdAssessedBy": {         "Id": "00000000-0000-0000-0000-000000000000",         "DisplayName": null,         "_links": [],         "_embedded": null     },     "FormResultAspNetUserCreatedBy": "example@domain.com",     "FormResultIsRequiredBySystem": false,     "FormResultASMTFormVersionId": "9780546d-4f56-e711-8187-025500ccdddb",     "Data": null,     "ParentEntityId": null,     "_links": [],     "_embedded": null }
Note: The response for a request that has performed updates may not include all information for the assessment form result. A subsequent request to the endpoint GET /api/v2/assessmentformresult/{id} following an update may be required to validate the outcome of a request.